Using .kzb binaries

Kzb binaries contain contents of your Kanzi Studio projects. To run your Kanzi application on a device, you need to export it as a .kzb binary.

When user starts a Kanzi application, Kanzi loads the content of one or more .kzb binaries. Kanzi loads the content to RAM and GPU memory when it needs to render it. See Resource management.

You can configure your Kanzi application:

In the C++ application in the onConfigure() function.
In application.cfg by setting the parameters for Kanzi Studio projects with or without C++ application.

See Reference for application configuration.

Creating a .kzb binary from a Kanzi Studio project

To create a .kzb binary from a Kanzi Studio project, open your Kanzi Studio project and select File > Export KZB > Export KZB Binary.

Kanzi Studio creates these files:

<ProjectName>.kzb contains the content of your project in binary format.
<ProjectName>.kzb.txt contains a list of paths to project items in the .kzb binary. You can use these paths to access the content of your Kanzi application in the application code.
<ProjectName>.kzb.cfg contains a list of .kzb binary files. If your Kanzi application includes application code, Kanzi by default configures the C++ application to load the binaries listed in this file
```
configuration.binaryName = "<ProjectName>.kzb.cfg"
```

If you export the .kzb binary of a Kanzi Studio project without C++ application, Kanzi Studio creates these files in <KanziWorkspace>/Projects/<ProjectName>/Binary, otherwise it creates these files in <KanziWorkspace>/Projects/<ProjectName>/Application/bin.

Creating an application from .kzb binaries from several Kanzi Studio projects

You can create a Kanzi application that loads its content from more than one .kzb binary. This way you can combine multiple Kanzi Studio projects into one Kanzi application when a user starts your Kanzi application.

When you want to use the same scene graph for your Kanzi application, use the same project name for all the projects you want to combine into one Kanzi application. When combining projects with the same name, each project item in the same location of the scene graph and the same name as a project item in another .kzb file is overwritten by the item from the .kzb file that is listed last in the .kzb.cfg file. For example, if you have two .kzb files named ProjectOne and each contains an object named Screen in the same location in the scene graph, Kanzi uses the Screen object contained by the project listed last in the .kzb.cfg. You can achieve a similar result by merging several Kanzi Studio projects in Kanzi Studio. See Merging projects.

When you want to use different scene graphs for your Kanzi application, use different project names for each project you want to combine into a single Kanzi application. You can combine projects with different names only using the Kanzi API.

To create and application from .kzb binaries from several Kanzi Studio projects with different names:

Create a master project and export its .kzb binary. See Creating a .kzb binary from a Kanzi Studio project.
Because you combine multiple .kzb binaries using the Kanzi API, create your master project with a C++ application.
For example, create a project that contains just the loading screen of your Kanzi application.
Create the rest of your Kanzi application in one or more Kanzi Studio projects. In each project select Project > Properties and in the Properties disable the Master Project property.

In the project properties the properties listed in the category Binary Export contain settings for binary export. You can use these properties to optimize the performance of your application.
For example, create two Kanzi Studio projects:
- Name the first project Project one and in the Project > Prefabs create a Viewport 2D that contains a Text Block 2D, align the text to the top left corner and set the Text property to Project one.
- Name the second project Project two and in the Project > Prefabs create a Viewport 2D that contains a Text Block 2D, align the text to the top right corner and set the Text property to Project two.
In each Kanzi Studio project you want to use with your master project select File > Export KZB > Export KZB Binary.
Kanzi Studio creates a .kzb binary with configuration files. If you export the .kzb binary of a Kanzi Studio project without C++ application, Kanzi Studio creates these files in <KanziWorkspace>/Projects/<ProjectName>/Binary, otherwise it creates these files in <KanziWorkspace>/Projects/<ProjectName>/Application/bin.
Place the .kzb binaries you exported in the previous step to the <KanziWorkspace>/Projects/<ProjectName>/Application/bin directory of your master project.
In the Project > Properties you can set the Binary Export Directory property to export the kzb binary directly to the <ProjectName>/Application/bin directory of your master project.
Add the .kzb binaries to the .kzb.cfg file of your master project.
For example, if your master project is called Loading screen, and you are loading projects with names Project one and Project two, the .kzb.cfg file of your master project looks like this
```
Loading_screen.kzb
Project_one.kzb
Project_two.kzb
```

In Visual Studio open the Visual Studio solution for your application located in <ProjectName>/Application/configs/platforms/win32. In the C++ application code of your master project, create a function that loads the additional binaries.
For example, if your master .kzb binary contains only a loading screen and you want to load two .kzb binaries that contain the content, in the C++ application of the master project:

Include the required headers.
The headers you need to include depend on the content of the .kzb binaries you want to include in your Kanzi application.

// During development use the general kanzi.hpp header that covers
// the majority of cases. For production use only the headers that
// are used by your binaries.
#include <kanzi/kanzi.hpp>

In the main class of application use the onProjectLoaded() virtual function to load the content from the additional binaries. Kanzi calls the onProjectLoaded() function after loading all kzb binaries.

    virtual void onProjectLoaded() KZ_OVERRIDE
    {
		ResourceManager* resourceManager = getDomain()->getResourceManager();

		// First binary
		// Load the Viewport 2D prefab template named Viewport 2D from the first
		// binary using the kzb URL.
		PrefabTemplateSharedPtr viewportPrefabOne = resourceManager->acquireResource<PrefabTemplate>("kzb://Project one/Prefabs/Viewport 2D");

		// Instantiate the loaded prefab and name the instance Viewport one.
		Viewport2DSharedPtr viewportOne = viewportPrefabOne->instantiate<Viewport2D>("Viewport one");

		// Add the instantiated prefab as a child of the root of the scene graph
		// in the master project.
		getRoot()->addChild(viewportOne);

		// Second binary
		// Load the Viewport 2D prefab template named Viewport 2D from the second
		// binary using the kzb URL.
		PrefabTemplateSharedPtr viewportPrefabTwo = resourceManager->acquireResource<PrefabTemplate>("kzb://Project two/Prefabs/Viewport 2D");

		// Instantiate the loaded prefab and name the instance Viewport two.
		Viewport2DSharedPtr viewportTwo = viewportPrefabTwo->instantiate<Viewport2D>("Viewport two");

		// Add the instantiated prefab as a child of the root of the scene graph
		// in the master project.
		getRoot()->addChild(viewportTwo);
	}

In Visual Studio select one of the solution configurations for your version of Visual Studio and run your application.
For example, if you are still developing your application, select the GL_vs2010_Debug configuration. If you want to create a production version of your Kanzi application, select one of the available release configurations.

Using .kzb binaries

Creating a .kzb binary from a Kanzi Studio project

Creating an application from .kzb binaries from several Kanzi Studio projects

See also